package org.mediahouse.trac.http;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
 * @author Tin
 * @version %I%, %G%
 * 
 */
public interface CustomHttpServlet {

    /**
     * The main request handler of classes implementing the
     * {@code CustomHttpServlet} interface. This method is intended to fulfill
     * any incoming HTTP request to the HttpServlet instance. The core functions
     * of this HttpServlet are defined here. Implementations of this interface
     * are required to override this method.
     * <p>
     * The specific method type of the incoming request is specified by the
     * invoking container whenever it forwards requests to this handler, by
     * overloading the method call with a {@code method} parameter. It is still
     * possible to have each request method provide a customized response that
     * is not bound to this handler, by overriding the relevant method from the
     * base HttpServlet class (i.e. the {@code doPost, doGet, doPut} methods
     * etc.). If overridden the base request handler will no longer redirect to
     * this handler unless explicitly implemented to do so.
     * 
     * @param request
     *            HttpServletRequest object passed in with the request
     * @param response
     *            HttpServletResponse object passed in with the request
     * @param method
     *            One of the accepted HTTP request methods specified in
     *            {@link HttpRequestMethodType} that corresponds to the incoming
     *            request
     * @throws Exception
     *             optionally, if the request handler method may produce an
     *             exception under any circumstances
     */
    public abstract void doRequest(final HttpServletRequest request,
            final HttpServletResponse response, final HttpRequestMethodType method) throws Exception;

    /**
     * @author Tin
     * @version %I%, %G%
     * 
     */
    public enum HttpRequestMethodType {
        DELETE, GET, HEAD, OPTIONS, POST, PUT, TRACE;

    }

}